home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / mxlibs / sbdsp2b / sbdsp.txt < prev    next >
Text File  |  1995-02-11  |  22KB  |  429 lines
  1. *****************************************************************************
  2. *                           SBDSP Read Me file                              *
  3. *                           ==================                              *
  4. *                                                                           *
  5. *        SBDSP is Copyright (C) 1994, 1995 by Romesh Prakashpalan,          *
  6. *                         all rights reserved                               *
  7. *****************************************************************************
  8.  
  9. Table Of Contents:
  10. ==================
  11.  
  12.    1) Introduction to SBDSP
  13.    2) Features and System Requirements
  14.    3) Getting Started
  15.    4) Modifications necessary to work with Turbo Pascal 6.0
  16.    5) Implementing REAL TIME FX
  17.    6) Structure of the RPD file format
  18.    7) Notes on the future + Contacting the author
  19.  
  20. *****************************************************************************
  21. *                         Introduction to SBDSP                             *
  22. *****************************************************************************
  23.  
  24.   SBDSP is a Pascal Unit that allows one to utilize the FULL power of the
  25. Sound Blaster's Digital channel. At one stage in my game programming projects
  26. I realized that I was going to need digital sound and music in my games!
  27. After all, the PC Speaker was just NOT going to be good enough for a
  28. production level game (BTW, I still haven't released anything as of this
  29. writing), but to my dismay, all of the books and literature seemed to use the
  30. darn libraries that Creative ships with "genuine" (albeit noisy) Sound Blasters.
  31. This meant that people without the drivers would not be able to run my
  32. programs! So, I contacted Creative, and found out that their developer's kit
  33. costs 100 U.S Dollars! I then hunted on the Internet, and found a few docs
  34. here and there, and I eventually managed to create the SBDSP and SBFM
  35. libraries. Anyways, I am releasing this unit to the public for those who need
  36. the capability of digital sound, and my code surpasses the information found
  37. in the SDK made by Creative. There are 2 Programs attached to the SBDSP unit
  38. itself, and those illustrate how to play back and record a sample (from
  39. Disk).
  40.  
  41.   The rest of this document will give some information on the unit, as well
  42. as file formats utilized (RPD), and some tips on REAL TIME FX.
  43.  
  44.                                          - Romesh Prakashpalan (1/23/95)
  45.                                           (hacscb93@huey.csun.edu)
  46.  
  47. Disclaimer: The author (Romesh Prakashpalan) specifically disclaims
  48. ==========  responsibility for any loss of profit or any consequential,
  49.             incidental, or other damages. The Turbo Pascal code attached to
  50.             this document is FREEWARE and includes the following programs/
  51.             units/files:
  52.                (SBDSP.PAS   - Turbo Pascal Unit)
  53.                (VOC2RPD.PAS - Turbo Pascal Program)
  54.                (WAV2RPD.PAS - Turbo Pascal Program)
  55.                (RPD2VOC.PAS - Turbo Pascal Program)
  56.                (TESTDSP.PAS - Turbo Pascal Program Demonstrating Playback)
  57.                (RECDSP.PAS  - Turbo Pascal Program Demonstrating Recording)
  58.                (SBDSP.TXT   - This Document)
  59.  
  60.             These programs/units can be incorporated in your programs in full/
  61.             partial form, but this package is NOT to be distributed modified!
  62.             If you feel as if this package needs changing, contact me, and we
  63.             can work on changes TOGETHER, and release a new version.
  64.  
  65. P.S: If you feel as if this unit is worth some money, please send some over
  66.      my way ;-) This way, I can fund my research and game programming projects,
  67.      and upgrade my computer. Or, at the very least include my name in the
  68.      credits section of whatever you release that uses the SBDSP unit. But,
  69.      note that a donation is NOT necessary, as this is FREEWARE, not
  70.      SHAREWARE!
  71.  
  72. *****************************************************************************
  73. *                   Features implemented in SBDSP 2.0ß                      *
  74. *****************************************************************************
  75.   [X] FULL Support for the Sound Blaster DSP chip
  76.   [X] DIRECT ACCESS to the Sound Blaster, none of Creative Lab's drivers are
  77.       needed!
  78.   [X] DMA Driven, no CPU intervention neccessary
  79.   [X] Play from Disk w/a small buffer in memory (File can be any size, but
  80.       Buffer is <= 64K).
  81.   [X] Double Buffering implemented in order to reduce "clicks"
  82.   [X] Play straight from memory (up to 64K)
  83.   [X] Software mixing of samples
  84.   [X] Stereo output for the SB-PRO or higher
  85.   [X] Full support for the SB-PRO mixer chip
  86.   [X] Conversion from the most popular PC Sound Formats (VOC, WAV)
  87.   [X] Conversion to the VOC file format
  88.   [X] Real Time Software Volume adjustment
  89.   [X] Recording option (8-bit), and supports the SB-PRO filters, and is
  90.       capable of switching from Line-In, Mic and CD inputs (SBPRO or higher)
  91.   [X] DOS Re-entrancy problem "appears" to have been fixed.
  92.  
  93. *****************************************************************************
  94. *        Features NOT implemented in 2.0ß (but will be in 2.0)              *
  95. *****************************************************************************
  96.   [ ] 16 bit sound will be included in 2.0 (final release)
  97.   [ ] Surround Sound MIGHT be included (I'm not sure, as I'll have to allocate
  98.       buffers dynamically which might be detrimental to a Real Mode program.
  99.  
  100. *****************************************************************************
  101. *                         System Requirements                               *
  102. *****************************************************************************
  103.   [ ] IBM PC Compatible with a 80386 processor or higher
  104.   [ ] Sound Blaster Card, Pro required for Stereo output, and 16 required for
  105.       16-bit playback
  106.   [ ] AT LEAST 16K of memory set aside for Double Buffering (buffers can be
  107.       smaller, but system performance and sound quality will degrade)
  108.   [ ] Turbo Pascal V7.0 (can run in 6.0 with minor modifications)
  109.   [ ] A Human (or any sentient being) required to appreciate the sounds ;-)
  110.  
  111. *****************************************************************************
  112. *                           Getting Started...                              *
  113. *****************************************************************************
  114.  
  115. I) Playing a file from disk...
  116.  
  117.   OK, now you have the unit, and have all of the system requirements, so
  118. how do we output a simple sound? If you have a favorite VOC or WAV file,
  119. convert it to a RPD file first, and make sure that it falls in the following
  120. parameters:
  121.  
  122.   [ ] 8-bits/sample in Stereo/Mono in any sample rate (make sure that your
  123.       harware can actually play sounds of this type first!)
  124.  
  125.   Then, in the beginning of your program (or anywhere before actually using
  126. the Sound Card), use the ResetDSP command:
  127.  
  128.    ResetDSP (BaseAddress, IRQ, DMAChannel, HighDMAChannel);
  129.  
  130.       Where Base =  1 for 210h
  131.                     2 for 220h
  132.                     3 for 230h, etc...
  133.  
  134.       IRQ is typically 7 for older cards, and 5 for the newer ones
  135.       DMAChannel is usually 1 (SB16 owners note this is the LOW DMA channel)
  136.       HighDMA is usually 5 for SB16 owners, people without a SB16 (or AWE32),
  137.               should leave this at 0.
  138.  
  139. Then, we just use the following command to play the RPD file:
  140.   PlaySoundRPD (Filename);
  141.  
  142.   Where Filename is the name of your sound file (RPD). The Sound will be played
  143. in the background, while your program is free to do what it wants in the
  144. foreground. So, if you have a loop similiar to this:
  145.  
  146.   PlaySoundRPD (Filename)
  147.   While SomeCondition do
  148.   Begin
  149.     (* Do something *)
  150.     If not Playing then
  151.       PlaySoundRPD (SomeOtherFile);
  152.   End
  153.  
  154.   This above loop is the basis of a "JukeBox" type app, where when the sound
  155. is done playing, we load in the next song in the list. NOTE: The playing
  156. variable indicates if a sample is still playing over the Sound Card.
  157.  
  158. II) Playing a Sound from Memory.
  159.   The above procedure works just great for long samples (speech, music), but
  160. what about when we want to play a sample from memory repeatedly? When I say
  161. repeatedly, I mean something like a machine gun shot, it would sound lousy,
  162. and be pretty inefficient if we had to load the sound from disk every time
  163. the user presses the fire button! That's why we have another function called:
  164.   LoadSoundRPD (Filename, SoundBuffer, AllocMem);
  165.  
  166.   Where Filename is the name of your file, SoundBuffer is a buffer in memory
  167. of type: BaseSoundType, and AllocMem is True if you want the procedure to
  168. allocate memory for you, else it is False.
  169.  
  170. First, we issue the LoadSoundRPD command:
  171.   LoadSoundRPD (Filename, SoundBuffer);
  172.  
  173.   Now, we have the sound safely stored in a buffer in memory ready for the
  174. PlaySound command whenever we want to play it back!
  175.  
  176.   So, we can have a loop like this:
  177.  
  178.   LoadSoundRPD (Filename, BulletBuffer, True);
  179.   While Somecondition do
  180.   Begin
  181.     If (FireButtonPressed) and (not Playing) then
  182.       PlaySound (BulletBuffer);
  183.   End;
  184.   { Free the memory allocated: }
  185.   FreeMem (BulletBuffer.Buffer, BulletBuffer.BufferSize);
  186.  
  187. III) Recording a sample to disk:
  188.   Version 2.0ß was the first to implement recording (to disk), and was
  189. implemented for someone who needed it urgently. So, the recording function is
  190. less than perfect.
  191.  
  192.   The steps needed for recording to disk are:
  193.     1) * Set Input source via the SetInputSource command
  194.     2) * Set Volume level for your input source via one of the following
  195.          commands:
  196.            - SetMicVolume
  197.            - SetLineInVolume
  198.            - SetCDVolume
  199.     3) Issue the RecordSoundRPD command:
  200.          RecordSoundRPD (Filename, Freq);
  201.  
  202.          Where Filename is the Filename to be recorded to, and Freq is the
  203.          Frequency at which you want to sample at.
  204.  
  205.     4) When you are done, issue the StopRecording command, and the file will
  206.        be closed, and all info will be saved for future use.
  207.  
  208.     Note: Items marked with a * are only available on the SB-PRO or higher!
  209.  
  210. Problems with recording option:
  211.   1) Currently only supports 8 bit mono.
  212.   2) Will write ALL of the last buffer in memory to disk, so it takes up more
  213.      disk space than necessary (File Size = N*BufferSize + SizeOf (Header)).
  214.      Where N is the number of times the buffer has been recorded to.
  215.  
  216. IV) Tweaking for optimum performance:
  217.   If you look at the interface section, you will notice two procedures:
  218. CheckBufferSize and ChangeBufferSize. These two procedures will return and
  219. change the Size of the Double Buffer. Experience has shown that buffer sizes
  220. in the range of 8K (for mono 11Khz at 8bits/sample) -> 64K (stereo 44.1Khz)
  221. are the best ranges (BTW: 64K is the MAXIMUM buffer size). ChangeBufferSize
  222. returns True if the buffer size was changed successfully, and False otherwise.
  223. The only time it will return False is if you are recording/playing back a
  224. sample. CheckBufferSize simply returns the size of the allocated buffer in
  225. memory.
  226.  
  227. *****************************************************************************
  228. *           Modifications necessary to work with Turbo Pascal 6.0           *
  229. *****************************************************************************
  230.   So, you say that you have Turbo Pascal 6.0, and the unit gives you a few
  231. errors when you want to compile? Well, then this section is for you:
  232.  
  233.   SBDSP 2.0ß was made to run/compile under Turbo Pascal version 7.0, so a
  234. few changes are necessary in order to make it work with Turbo Pascal 6.0.
  235. (Note: I myself upgraded from 5.5 to 7.0, and NEVER had 6.0, so this is
  236.        based on discussions with my friends who had Turbo Pascal 6.0)
  237.  
  238. First: SBDSP requires use of the In Line Assembler, so it is incompatible
  239.        with versions of Turbo Pascal < 6.0, so an assembly module would
  240.        be required in order to get the same functionality out of it if you
  241.        are using Turbo Pascal 5.5 or lower.
  242.  
  243.        As far as I know, Turbo Pascal 6.0 DID NOT have the PChar type. For
  244.        those of you who have Turbo Pascal 6, PChar is a string type similar
  245.        to that of C's. In TP 7.0, pointer arithmetic is ONLY defined for this
  246.        type, so it makes it quite convenient to use this type when dealing
  247.        with pointers! I have made use of this type in the following procedures:
  248.  
  249.             ChangeSampleVol
  250.             MixSamples
  251.  
  252.        Now, fixing this in Turbo Pascal 6.0 would require the following
  253.        changes:
  254.  
  255.          In the interface section of the unit create a new type definition:
  256.            CharArr = Array [0..$FFFE] of Char;
  257.            PChar = ^CharArr;
  258.  
  259.          Now, anytime where we see a variable of PChar type being referenced
  260.          as an array, reference it as a POINTER ARRAY. For instance, in my
  261.          code when you see: TempC[I] := Char (20);
  262.          Change this to: TempC^[I] := Char (20);
  263.  
  264.     If at any time, you get a "type mismatch" error when passing pointers,
  265.     just re-cast your pointer to the PChar type -> PChar (YourPointer), and
  266.     this should do the trick!
  267.  
  268.     There's one last thing, TP 6.0 doesn't default to having EXTENDED SYNTAX
  269.     ON, so make sure that the {$X} switch is on: {$X+}, as TP 6.0 defaults
  270.     to {$X-}
  271.  
  272.     This should be all for owners of Turbo Pascal 6.0, but I could be wrong,
  273.     as I don't have the Compiler myself, so if anything gives you any troubles,
  274.     mail me, and I shall try to find out what is wrong...
  275.  
  276.     Borland Pascal 7.0 should NOT be used to create PROTECTED MODE programs
  277.     with this unit, as it works with Segments:Offsets in REAL MODE, and NOT
  278.     with Selectors and Offsets! You will get really screwed up sound output
  279.     if you do try to use the unit with BP 7.0, so beware!
  280.  
  281. *****************************************************************************
  282. *                       Implementing REAL TIME FX                           *
  283. *****************************************************************************
  284.  
  285.   For those of you interested in doing REAL TIME FX, a few guidelines follow:
  286.  
  287. First, you have to know how the data is stored, FX engines have to work with
  288. uncompressed samples in order to work at all (unless you have a DSP chip, and
  289. know how to program it). Eight bit samples are ideal for this purpose. The
  290. data is stored as a series of unsigned 8-bit quantities in the RPD file. This
  291. means that we can have a resolution of 1 part in 256 (0 - 255). Consequently,
  292. all transformations have to be done in this range, or else we will get VERY
  293. distorted results. The way my SBDSP unit works is as follows:
  294.  
  295.   I)  We have a buffer of up to 64K in memory.
  296.        a) This Buffer is "split" into 2 chunks, Buffer1 and Buffer2.
  297.        b) When Buffer1 is playing, Buffer2 is being loaded from disk, and vice
  298.           versa.
  299.  
  300.   II) After a certain buffer is loaded from disk, THAT is the ideal time to do
  301.       our operations on it (this is what makes it REAL TIME).
  302.  
  303. Since we are using DMA xfers (that don't need CPU intervention within a buffer)
  304. this technique works well. For a VERY simple FX, try to understand my VOICE
  305. AMPLIFICATION Function, this is a very simple function to get started on.
  306.  
  307. The above technique works well if you are using a reasonable buffer size, and
  308. the operations that you perform are not TOO complicated (unless of course, you
  309. are using a Pentium(TM) Processor ;-) ).
  310.  
  311. *****************************************************************************
  312. *                   Structure of the RPD file format:                       *
  313. *****************************************************************************
  314.  
  315.   The RPD file format was created by myself as an alternative sound format for
  316. games (mine in particular). I got tired of reading in complicated VOC files,
  317. and WAV files (WAV files are easier, but are still too much for a game). So,
  318. I created a new file format for myself, as well as tools to convert from the
  319. VOC and WAV file formats to RPD. I had no idea how popular that my Sound
  320. Library would become (about 100 people wanted/got my Library in the space of
  321. a couple of months), so I have started bundling the VOC2RPD and WAV2RPD programs
  322. with SBDSP. Version 2.0ß will also have a converter that converts a RPD file
  323. to the VOC and/or WAV file formats. But, people need to know the basic
  324. structure of the RPD file format, so here it is:
  325.  
  326.                    RPD file format, version 1.01
  327.                    =============================
  328.  
  329.    Byte Offset                     Description
  330.    -----------                     -----------
  331.       0-2                      Signature -> "RPD"
  332.       3-4                      Version (1 Word), Lo Byte = Major Version,
  333.                                Hi Byte = Minor Version
  334.        5                       DAC Type (Bits/Sample), see table below
  335.        6                       Mono = 0, Stereo = 1, Surround = 2
  336.        7                       # of Digital Channels in the Sample
  337.        8                       Method of Laying down channels
  338.       9-12                     Size of sample (LongInt)
  339.        13                      Signed/Unsigned 16-bit sample (v1.01)
  340.                                  0 indicates a Unsigned sample (16-bit)
  341.                                  1 indicates a Signed sample   (16-bit)
  342.      14-44                     Reserved for future expansion
  343.      45-EOF                    Sample Data
  344.  
  345.  
  346.                            DAC Type Table:
  347.                            ===============
  348.  
  349.   DACType                               Description
  350.   -------                               -----------
  351.    0B6h                               Sixteen Bit Sound
  352.    014h                               Eight Bit Sound
  353.    016h                               Two Bit ADPCM compression
  354.    017h                               Two Bit ADPCM w/Reference byte
  355.    074h                               Four Bit ADPCM compression
  356.    075h                               Four Bit ADPCM w/Reference byte
  357.    076h                               2.6 Bit ADPCM compression
  358.    077h                               2.6 Bit ADPCM w/Reference byte
  359.  
  360.                              Channel Method
  361.                              --------------
  362.  
  363.    0 - Indicates that Channel 1 Byte comes first, then Channel 2 Byte, etc...
  364.    1 - Indicates that Channel 1 data comes for Sample Size bytes, then comes
  365.        Channel 2 data for Sample Size Bytes, etc...
  366.  
  367.    This is an example of the same file with different channel methods:
  368.  
  369.    Channel Method 0:
  370.      # of Channels = 3
  371.      Size of Sample = 1260
  372.  
  373. Byte:   0      1      2      3      4      5      6      7    ...  1260
  374.      +------+------+------+------+------+------+------+------+
  375.      | Ch 1 | Ch 2 | Ch 3 | Ch 1 | Ch 2 | Ch 3 | Ch 1 | Ch 2  ...
  376.      +------+------+------+------+------+------+------+------+
  377.  
  378.    Channel Method 1:
  379.  
  380.    # of Channels = 3
  381.    Size of Sample = 1260 / 3 = 420
  382.  
  383. Byte:0                419               838              1260
  384.      +-----------------+-----------------+-----------------+
  385.      | Ch 1            |  Ch 2           | Ch 3            |
  386.      +-----------------+-----------------+-----------------+
  387.  
  388. *****************************************************************************
  389. *                       Notes on the future...                              *
  390. *****************************************************************************
  391.  
  392.   This unit (2.0ß) is just a pre-release (ßeta), and a lot of the features
  393. that will/should be present in 2.0 are missing. Most notable of these is
  394. 16-bit sound. I am currently having some problems on 16-bit playback, so I
  395. do not have any release dates planned. Release 2.0 will also convert a 16-bit
  396. sound to 8-bit in Real Time (for users without a SB 16), so that you don't
  397. have to worry about what type of sound to use (but it won't sound good at all!)
  398. However, this unit does give you pretty much all you need in order to make a
  399. game/music player, and exploits all the capabilities of cards up to the Pro.
  400. This package as it stands is pretty general, and should cover all of your needs
  401. for digital sound playback. I am debating whether to implement EMS memory
  402. for storage of samples (instead of disk xfers, when there is enough room), as
  403. Turbo Pascal 7.0 makes this pretty painless with the TEMSStream object, but
  404. I'm not sure if TP 6.0 has this, and if it doesn't, then I will have widened
  405. the gap between the users of TP 6.0 and those who use TP 7.0 :-(. But, I have
  406. to remind myself that I'm not getting paid to do this, and this is my final
  407. semester. That by the way is the reason that I can't make the REAL version of
  408. this package (2.0) available before June! I'm taking 7 subjects + working
  409. 20hrs a week, so I'm exhausted mentally and physically by the time that I get
  410. home. Though I have to remind myself that people like Ethan Brodsky and myself
  411. are the only ones that are making Sound Libraries for *FREE*, and people
  412. depend on us for *good* quality code (even more important now that we have
  413. lost Mike Tedder to the GUS).
  414.  
  415.                                              - Romesh Prakashpalan
  416.                                                (hbcsc294@huey.csun.edu)
  417.                                                      02/11/95
  418.  
  419.                                              Or, write to me at the following
  420.                                              (snail mail) address:
  421.  
  422.                                                  17304 Westbury Dr.
  423.                                                Granada Hills, CA 91344
  424.                                                       U.S.A
  425.  
  426.   Software (C) 1995 by Romesh Prakashpalan, All rights reserved. IBM is a
  427. registered trademark of International Business Machines Corp. Pentium is a
  428. registered trademark of Intel Corp. Sound Blaster is a registered trademark
  429. of Creative Labs Corp.